\documentclass[a4paper,12pt]{article}

\usepackage[utf8x]{inputenc}
\usepackage{ucs}
\usepackage[francais]{babel}
\usepackage{fullpage}
\usepackage{uml}
\usepackage{ifpdf}
%\usepackage{titlesec}
\usepackage{color}
\usepackage{tikz}
\usepackage{verbatim}
\usepackage{fancyhdr}
\usepackage{lastpage}
\usetikzlibrary{arrows,%
				shapes,positioning}


\def\firstname{Yannis Mazzer and }
\def\familyname{Joe R. Nassimian}
\def\FileAuthor{\firstname \familyname}
\def\FileTitle{\firstname \space \familyname's LIF13 report}
\def\FileSubject{LIF13 report}
\def\FileKeyWords{\firstname \familyname, LIF13 report}

\renewcommand{\ttdefault}{pcr}

\usepackage{url}
\urlstyle{tt}
\ifpdf
  \usepackage[pdftex,pdfborder=0,colorlinks=true,linkcolor=blue,baseurl=http://,pdfpagemode=None,pdfstartview=XYZ,pdfstartpage=1]{hyperref}
  \hypersetup{
	colorlinks	= true, 
	linkcolor	= blue,  
	anchorcolor	= blue,  
	citecolor	= blue, 
	filecolor	= blue, 
	menucolor	= blue, 
	pagecolor	= blue,  
	urlcolor	= blue,
    pdfauthor   = \FileAuthor,%
    pdftitle    = \FileTitle,%
    pdfsubject  = \FileSubject,%
    pdfkeywords = \FileKeyWords,%
    pdfcreator  = \LaTeX,%
    pdfproducer = \LaTeX}
\else
  \usepackage[dvips]{hyperref}
\fi







\title{LIF13 -- Présentation du projet Jalokus}
\author{Yannis Mazzer and Joe R. Nassimian\\ 
\ifpdf
\includegraphics[width=100px] {./graphics/ucbl.jpg}
\fi}
\renewcommand\headheight{14pt}
\renewcommand\headsep{10pt}
\renewcommand\footrulewidth{0.4pt}
\pagestyle{fancy}
\fancyhf{}

%\lhead{\ifodd \today \else \rightmark \fi}
%\rhead{\ifodd \rightmark \else \today \fi}
%\rhead{\rightmark}
%\lhead{\today}
%\lfoot{\leftmark}
%\rfoot{\thepage / \pageref{LastPage} \space $\sim(\;,\;,">$}
%\rfoot{ $\sim(\;,\;,">$ \hspace{1cm} Page \thepage \hspace{3pt} sur \pageref{LastPage}}
\cfoot{\thepage}

\begin{document}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Commands and counters definitions %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\newcommand{\ra}{$\Rightarrow $}

\newcommand{\ras}{$\rightarrow $}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%             Document              %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\setcounter{tocdepth}{1}
\maketitle
\tableofcontents
%\listoffigures
%\listoftables
\clearpage

\section{Introduction}
Jalokus \cite{jalokus} est un projet universitaire de développement du jeu de Blokus \cite{blokus}.
Il s'inscrit dans le cadre de l'enseignement de LIF13 à l'Université Claude Bernard de Lyon.

Le Blokus est un jeu de plateau créé par Bernard Tavitian en 2000. Il se joue à 2 ou 4 joueurs.
Chaque joueur possède un nombre fixe de pièces de forme Tétrisoïdale. Les joueurs jouent chacun
leur tour jusqu'à ce qu'ils n'aient plus de pièce ou qu'ils ne puissent plus agir sur le damier. Le
but du jeu est d'avoir posé un maximum de pièces à la fin de la partie.

\section{Description des fonctionnalités}
\subsection{Résumé}
\begin{tabular}{|l|l|}
\hline
Fonctionnalité																		& Status \\
\hline
\hline 
Affichage d'une fenêtre principale 													& Fait \\
Affichage d'un damier																& Fait \\
Affichage amélioré (SVG) du damier à l'aide de la librairie Batik \cite{batik}		& Fait \\
Affiche d'une liste de pièces														& Fait \\
Affichage amélioré (SVG) d'une liste de pièces à l'aide de Batik \cite{batik}  		& Fait \\
Utilisation d'un Framework (JSR 296 \cite{jsr}) pour la gestion de l'application 	& Fait \\ 
Affichage d'un menu																	& Fait \\
Intégration de dialogues accessible via le menu										& Fait \\
Utilisation des Layout pour le positionnement des widgets							& Fait \\
Externalisation des informations relative à l'environnement de l'application		& Fait \\
Suivi du curseur par la pièce séléctionnée (sur le damier uniquement)				& Fait \\
Possibilité de positionner des pièces sur le damier									& Fait \\
Possibilité de tourner les pièces													& Fait \\
Vérification sémantique de la position de la pièce à poser							& Fait \\
\hline
\end{tabular}

\subsection{L'affichage}
\subsubsection{La fenêtre principale}
La fenêtre principale est composée de deux parties, la barre de menu et la zone 
de jeu. La barre de menu contient l'ensemble des menus qui permettent au joueur
d'effectuer des actions relatives à l'application :
\begin{itemize}
\item Le menu "Game"
\begin{itemize}
\item l'élément "New Game" permet de lancer le dialogue de configuration d'un 
nouveau jeu.
\item l'élément "Quit" permet de fermer l'application. Cependant compte-tenu
de la gestion de la mémoire effectuée par les machines virtuelles de java, il ne
faut pas s'étonner si ça segfault.
\end{itemize}
\item Le menu "Settings" est encore vide mais permettra par la suite d'afficher
des raccourcis pour lancer des jeux préconfigurés. Par exemple passer du jeu de 
Blokus au jeu d'échecs en un clic.
\item Le menu "Help" contient toutes les informations relatives à l'application.
\begin{itemize}
\item l'élément "About Jalokus" ouvre le dialogue "À propos".
\end{itemize}
\end{itemize}

La zone de jeu est composée de deux types de composants, voir la figure \ref{mainWindowLayout}. Un
damier et une liste de pièces. Le damier est unique par jeu tandis qu'il y a autant de listes de 
pièces qu'il y a de joueurs. Pour l'organisation des parties de la zone de jeu,
le GroupLayout semble être la meilleure solution. Et, même si elle est lourde de 
par sa redondance et sa difficulté de mise en place, c'est la seule qui 
permet d'obtenir une organisation à peu près potable en Java. 

\begin{figure}[htbp]
\caption[Schéma de l'organisation de la fenêtre principale]{Schéma de l'organisation de la fenêtre
principale}
%\label{Schéma de l'organisation de la fenêtre principale}
\begin{verbatim}
+------------------------------------------------------------+
| La barre de menu                                           |
+---------------+----------------------------+---------------+
|               |                            |               |
|               |                            |               |
|   Liste de    |                            |   Liste de    |
|    Pièces	    |                            |    Pièces     |
|      du       |                            |      du       |
|    Joueur 1   |                            |   Joueur 3    |
|               |                            |               |
|               |                            |               |
+---------------+           DAMIER           +---------------+
|               |                            |               |
|               |                            |               |
|   Liste de    |                            |   Liste de    |
|    Pièces     |                            |    Pièces     |
|      du       |                            |     du        |
|   Joueur 2    |                            |   Joueur 4    |
|               |                            |               |
|               |                            |               |
+---------------+----------------------------+---------------+
\end{verbatim}
\label{mainWindowLayout}
\end{figure}

Le nombre de listes de pièces est égal au nombre de joueurs défini dans les 
propriétés du jeu à sa création. Ainsi, si le nombre de joueur est 3, seulement
trois listes de pièces seront créées et affichées.

\subsubsection{Le damier}
Le damier est par défaut un carré de 400 cases (20$\times$20), il permet d'afficher l'ensemble des
pièces posées mais aussi la pièce en cours qui suit le curseur de la souris au dessus du damier.
Pour afficher le damier, plutôt que d'utiliser un GridLayout de JPanel, on utilise la librairie
Batik qui permet d'afficher un document SVG en Java. Cependant, à l'instar de tout le langage Java,
cette librairie est très mal implantée et implique de nombreux segfaults.

\subsubsection{Les dialogues}
\paragraph{Le dialogue ``Nouveau Jeu''}
affiche une fenêtre de configuration pour le jeu qui va être nouvellement lancé. Il demande les
information importantes relatives au jeu telles que le nombre de joueurs, le type de jeu et la forme
du damier (carrée, héxagonale, \dots). Lorsque le dialogue est accepté, si un jeu est en cours, il
est abandonné, et un nouveau jeu est créé.

\paragraph{Le dialogue ``À Propos''}
affiche les informations générales relatives à l'application :
\begin{itemize}
  \item Le logo 
  \item La version
  \item Le nom des auteurs
  \item Le nom de l'entreprise fictive qui vend ce projet open-source
  \item Un lien non cliquable (merci Java) vers la page web du projet
  \item La description du projet
\end{itemize}

\subsubsection{L'utilisation du Swing Application Framework}
Le \textsl{Swing Application Framework} (JSR-296) \cite{jsr} fournit une infrastructure de base
commune à la plupart des applications. Ainsi l'implantation de la fenêtre principale et du menu est facilitée.
Les ActionListeners sont déjà faits et on accroît significativement la productivité, car on se
concentre non plus sur l'incohérence, aussi bien syntaxique que sémantique, de Java, mais sur le
contenu de l'application.

\paragraph{Les ressources textuelles \\}
Le \textsl{Swing Application Framework} fournit une API pour récupérer des ressources 
stockées dans
des fichiers ``\textsl{Class}.properties''. De cette manière les informations telles que le titre de
l'application, le titre de chaque fenêtre, ainsi que les informations relatives à l'application (auteurs, version, 
etc \dots) sont stockées en dehors du code et peuvent être modifiées sans nécessiter de
re(-pseudo-)compiler le code. L'autre avantage considérable de la gestion des ressources via Swing
Application Framework est l'internationnalisation. Ainsi il n'est pas nécessaire d'implanter un
moteur de gestion de langue, c'est déjà fait (chose rare dans Java), il suffit de faire un
sélecteur de langue. 

\paragraph{Les Actions \\}
Au même titre que les ressources textuelles, les actions associées à un bouton,
par exemple, peuvent être stockées dans un fichier \textsl{Class}.properties.
Ainsi, lorsque l'action est effectuée par l'utilisateur, l'application va
chercher dans les ressources pour savoir quelle fonction il doit éxécuter. Et,
grand soulagement, on n'a pas à se préoccuper des ActionListeners qui
détruisent peu à peu tous les neurones que le développeur possède.

\section{Diagramme de classes commenté}
Ci-dessous se trouve les commentaires du diagramme de classe qui est en annexe \ref{classDiagram}.
\subsection{Main.class}
Main.class est la classe main principale de cette application Java qui se résume a
une ligne: La méthode static ``launch'' de Engine.class héritée de la super
classe Application.class du Framework JSR 296 qui se charge d'initialiser le
cycle de vie de l'application en lui précisant les arguments passés en paramètre.

\subsection{Engine.class}
Engine.class est le moteur de notre application au sens de JSR 296: C'est la
classe qui gère le cycle de vie de notre jeu composé en 6 grandes parties gérées
par les 6 methodes suivante:
\begin{enumerate}

   \item launch -- Il faut appeler cette méthode du framework (voir paragraphe
   précédent).
   \item initialize -- Le framework appellera cette méthode qui pourra
   facultativement être redéfinie. Dans notre cas, on récupère simplement les
   arguments passés en paramètre.
   \item startup -- Le framework invoquera cette méthode à définir: Initialise
   et met en place l'environnement de l'application et fini par lancer la
   fenêtre principale FirstView.class de l'application.
   \item ready -- Le framework invoquera cette méthode facultativement
   redéfinie. Ce n'est pas le cas dans notre application.
   \item exit -- La méthode du framework à appeler explicitement pour préparer
   la sortie de l'application proprement.
   \item shutdown -- Le framework invoquera cette méthode facultativement
   redéfinie.

\end{enumerate}

De plus, Egine.class est la classe ``Controller" principale qui se charge de
l'initialisation du jeu, comme la mise en place de l'environnement du jeu
selectionné dans JalokusNewGame.class et la gestion de la session du jeu.

\subsection{FirstView.class}
FirstView.class est une classr qui hérite de FrameView qui est une classr du
framework héritant de JPane avec quelques méthodes pratiques de plus. Ce
FirstView.class met en place la barre de menu, la barre de status, et les divers
titres de composants graphiques comme le titre de la fenêtre.

\subsection{PieceView.class}
PieceView.class est un JPanel qui contient un canvas SVG qui permet d'afficher une grille de taille
réduite par rapport au damier. Cette grille permet d'afficher chaque pièce du jeu de Blokus.

\subsection{PiecesView.class}
PiecesView.class est un JPanel qui contient un GridLayout, qui lui contient plusieurs PieceView.

\subsection{JalokusAbout.class}
JalokusAbout.class hérite de JDialog, et comme le nom le suggère, cette classe
permet de mettre en place la fenêtre de dialog ``A propos de Jalokus'' qui
contient des informations concernant le programme, comme le nom des auteurs
et l'adresse du site web (l'adresse de notre repositoire mercurial).

\subsection{JalokusNewGame.class}
JalokusNewGame.class hérite également de JDialog, pour afficher un dialogue au
démarrage et récupérer des informations de l'utilisateur, comme le nom du jeu,
la forme du plateau, la dimension de l'environnement (1D, 2D ou 3D) et le nombre
de joueurs. Ces informations sont ensuite envoyées vers Engine.class grâce à
la classe Settings.class pour créer une nouvelle session du jeu avec les
paramètres selectionnés.

\subsection{GamesList.class}
GamesList.class est un Hashtable qui à chaque jeu jouable sur ce moteur de jeu
de plateau associe les formes de plateau possibles, ce qui nous permettra de
rajouter par exemple la forme triangle pour le jeu du Blokus.

Le dialogue représentant JalokusNewGame.class exploite ce Hashtable pour
récupérer la liste des jeux avec la liste des formes de plateau pour chaque jeu.

\subsection{BoardSpecs.class}
BoardSpecs.class est un Hashtable qui à chaque dimension de plateau
(e.g. 2D) de jeu associe le nombre de pièces qu'on peut poser le long d'un côté
du plateau, ce qui nous permettra de rajouter par exemple la dimension 3D pour
le jeu du Blokus.

Le dialogue représentant JalokusNewGame.class exploite ce Hashtable pour
récupérer la liste des dimensions et la taille de plateau associées à chaque jeu et forme de
plateau.

\subsection{ShapeSpecs.class}
BoardSpecs.class est un Hashtable qui lie GamesList.class a BoardSpecs.class:
pour un jeu et une forme donnés par GamesList.class, ShapeSpecs.class permet de
récupérer un BoardSpecs.class, avec les informations concernant les dimensions
et tailles possibles pour le plateau.

Le dialogue représentant JalokusNewGame.class exploite ce Hashtable pour
récupérer un BoardSpecs à partir d'un GamesList.class.



\subsection{Settings.class}
Settings.class est une simple classe contenant les différentes données
récupérées par le dialogue représentant JalokusNewGame.class, et exploitée par
Engine.class pendant l'initialisation de la session de jeu.

\subsection{BoardGame.class}
BoardGame.class est une super classe construite suite à la mise en commun des
differents aspect des jeux à plateau et ceci dans le but de pouvoir rajouter
des jeux et des variantes de jeu avec un travail et un temps de
développement réduit. Cette classe permet donc d'avoir un plateau, et des
joueurs.

\subsection{Blokus.class}
Blokus.class hérite de GameBoard.class, vu que Blokus est un jeu de plateau.

\subsection{Board.class}
Board.class est une classe qui représente le plateau dans la partie modèle du
programme. Quand une pièce est placée sur le plateau, la sauvegarde de ce
changement se fait par une instance de cette classe.

\subsection{Player.class}
La class Player.class permet de gérer les informations concernant les joueurs,
comme la liste des pièces, le score courant du joueur et le nom.

\subsection{PlayerSon.class}
PlayerSon.class est une classe de factorisation d'attributs et méthodes. Elle permet notamment pour
toute classe qui représente une ``possession'' d'un joueur de récupérer le joueur auquel elle
appartient. Elle permet aussi de factoriser le caractère Observable. Ainsi les classes Pieces.class
et PiecesList.class héritent de PlayerSon.

\subsection{Piece.class}
Piece.class permet de représenter une pièce, avec des informations sur la
nature de la pièce comme le type de pièce, ou l'espace occupé par la piece sur
le plateau.

\subsection{PiecesList.class}
PiecesList.class permet de représenter une liste de pièces rangée par type, et
qui permet d'associer un joueur a un ensemble de pièces.

\section{Un scénario d'utilisation}
\subsection{Le démarrage de l'application}
Au lancement de l'application, la fenêtre principale est affichée, cependant pour que le
moteur de jeu sache ce qu'il doit créer, la boîte de dialogue de création de nouveau jeu est
affichée. L'utilisateur doit alors séléctionner un nombre de joueurs, un type de jeu, et une forme
de damier puis cliquer sur ``Ok'', le jeu peut ainsi commencer.

\subsection{Le déroulement du jeu}
La boucle de jeu gère les tours des joueurs, et utilise la barre de status de l'interface graphique
pour prévenir les joueurs. Pour jouer, il suffit au joueur courant de sélectionner la pièce dans sa
liste de pièces, en cliquant dessus, et de la poser sur le damier en cliquant sur une position
libre. Attention, si la position n'est pas libre, i.e. si au moins une des cases de la pièce est
rouge, la pièce ne sera pas posée.

\section{Améliorations possibles}
Le modèle de notre application a été créé pour être un minimum générique, il a été conçu pour être
évolutif et permettre à l'application de s'étendre outre l'implantation d'un jeu de Blokus. En
effet, il permet d'implanter plusieurs jeux de plateau tels que les échecs, le backgammon, et tout
autre jeu à base de plateau et de pièces. Il faut pour cela étendre l'application avec un nouveau
module de règles (différent de celui du Blokus), un nouveau damier, etc \dots Cependant tous ces
nouveaux modules hériteront les principaux attributs et méthodes des classes déjà implantées.

Outre l'extension du type de jeu, le modèle permet aussi de jouer à des jeux dont la dimension est
différente de celle du Blokus, par exemple un Blokus 3D. Il faudrait pour cela étendre les classes
déjà éxistantes. Notamment implanter un modèle de damier en 3D et un afficheur de celui-ci. Il
faudrait faire de même pour les pièces.


\section{Conclusion}
Ce projet a présenté plusieurs défis aussi bien personnels que techniques.
Nous avons tous les deux commencés avec un autre binôme de niveau moindre pour
respecter le souhait de notre professeur encadrant. Cependant, suite à une
absence totale de motivation et de productivité de leur part, nous avons décidé de fusionner nos
projet afin de pouvoir le terminer en respectant les délais imposés.

Le langage Java est sensé être simple, robuste et flexible. Ce projet nous a néanmoins démontré
le contraire. La documentation est dense mais de médiocre qualité, les ouvrages aussi bien que les
forums ne présentent aucune aide tangible dû au manque de rigueur des personnes les rédigeant.
Malgré cela nous avons tenté d'obtenir le meilleur de cette anti-solution :
\begin{itemize}
  \item Un environnement graphique dynamique et vectoriel.
  \item Un code facile à maintenir pour des futurs développements.
  \item Une utilisation de la mémoire minimale et intelligente (non Java n'en
  est pas capable malgré ce que nous avons vu en cours).
  \item Une compléxité algorithmique minimale et une exploitation du multi-threading
  pour une meilleure rapidité d'éxécution.
\end{itemize}

Afin de répondre à ce critère nous avons dû trouver des solutions.
Nous avons utilisé un framework (JSR 296) qui est non seulement exploité par
Netbeans pour créer des applications Swing, mais sera aussi intégré
dans Java 7 qui sortira fin 2010. Cela nous a permis de nous
concentrer sur le contenu de notre projet, plutôt que la syntaxe et la sémantique
irrationnelles de Java.

De plus pour la partie graphique, nous avons utilisé Batik, une librairie SVG qui permet de
générer et afficher des dessins vectoriels. Cette solution a l'avantage d'avoir un ``binding''
avec Swing pour intégrer plus facilement, tout du moins aussi facilement que cela puisse être fait
en Java, les objets Batik à l'interface.


\appendix

\listoffigures
\listoftables
\begin{figure}[htbp]
\caption[Diagramme de classes]{Diagramme de classes}
\label{classDiagram}
\ifpdf
\includegraphics[scale=0.70]{./graphics/fig128076}
\fi
\end{figure}




\nocite{*}
\bibliographystyle{plain}
\bibliography{report}

\end{document}
